syntax = "proto3";

// GRPC package - part of the URL. Service is added.
// URL: /PACKAGE.SERVICE/METHOD
package envoy.service.discovery.v3;

import "google/protobuf/any.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";

option go_package="github.com/envoyproxy/go-control-plane";

message Status {
    // The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
    int32 code = 1;

    // A developer-facing error message, which should be in English. Any
    // user-facing error message should be localized and sent in the
    // [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
    string message = 2;

    // A list of messages that carry the error details.  There is a common set of
    // message types for APIs to use.
    // google.protobuf.Any
    repeated google.protobuf.Any details = 3;
}


message Node {
    // An opaque node identifier for the Envoy node. This also provides the local
    // service node name. It should be set if any of the following features are
    // used: :ref:`statsd <arch_overview_statistics>`, :ref:`CDS
    // <config_cluster_manager_cds>`, and :ref:`HTTP tracing
    // <arch_overview_tracing>`, either in this message or via
    // :option:`--service-node`.
    string id = 1;

    // Defines the local service cluster name where Envoy is running. Though
    // optional, it should be set if any of the following features are used:
    // :ref:`statsd <arch_overview_statistics>`, :ref:`health check cluster
    // verification <config_cluster_manager_cluster_hc_service_name>`,
    // :ref:`runtime override directory <config_runtime_override_subdirectory>`,
    // :ref:`user agent addition <config_http_conn_man_add_user_agent>`,
    // :ref:`HTTP global rate limiting <config_http_filters_rate_limit>`,
    // :ref:`CDS <config_cluster_manager_cds>`, and :ref:`HTTP tracing
    // <arch_overview_tracing>`, either in this message or via
    // :option:`--service-cluster`.
    string cluster = 2;

    // Opaque metadata extending the node identifier. Envoy will pass this
    // directly to the management server.
    google.protobuf.Struct metadata = 3;

    // Locality specifying where the Envoy instance is running.
    //Locality locality = 4;

    // This is motivated by informing a management server during canary which
    // version of Envoy is being tested in a heterogeneous fleet. This will be set
    // by Envoy in management server RPCs.
    string build_version = 5;
}

// Binary compatible with DiscoveryRequest, with payload extension
message DiscoveryRequest {
    // The version_info provided in the request messages will be the version_info
    // received with the most recent successfully processed response or empty on
    // the first request. It is expected that no new request is sent after a
    // response is received until the Envoy instance is ready to ACK/NACK the new
    // configuration. ACK/NACK takes place by returning the new API config version
    // as applied or the previous API config version respectively. Each type_url
    // (see below) has an independent version associated with it.
    string version_info = 1;

    // The node making the request.
    Node node = 2;

    // List of resources to subscribe to, e.g. list of cluster names or a route
    // configuration name. If this is empty, all resources for the API are
    // returned. LDS/CDS expect empty resource_names, since this is global
    // discovery for the Envoy instance. The LDS and CDS responses will then imply
    // a number of resources that need to be fetched via EDS/RDS, which will be
    // explicitly enumerated in resource_names.
    repeated string resource_names = 3;

    // Type of the resource that is being requested, e.g.
    // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This is implicit
    // in requests made via singleton xDS APIs such as CDS, LDS, etc. but is
    // required for ADS.
    string type_url = 4;

    // nonce corresponding to DiscoveryResponse being ACK/NACKed. See above
    // discussion on version_info and the DiscoveryResponse nonce comment. This
    // may be empty if no nonce is available, e.g. at startup or for non-stream
    // xDS implementations.
    string response_nonce = 5;

    // This is populated when the previous :ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>`
    // failed to update configuration. The *message* field in *error_details* provides the Envoy
    // internal exception related to the failure. It is only intended for consumption during manual
    // debugging, the string provided is not guaranteed to be stable across Envoy versions.
    // google.rpc.Status
    Status error_detail = 6;
}

message DiscoveryResponse {
    // The version of the response data.
    string version_info = 1;

    // The response resources. These resources are typed and depend on the API being called.
    // google.protobuf.Any
    repeated google.protobuf.Any resources = 2;

    // [#not-implemented-hide:]
    // Canary is used to support two Envoy command line flags:
    //
    // * --terminate-on-canary-transition-failure. When set, Envoy is able to
    //   terminate if it detects that configuration is stuck at canary. Consider
    //   this example sequence of updates:
    //   - Management server applies a canary config successfully.
    //   - Management server rolls back to a production config.
    //   - Envoy rejects the new production config.
    //   Since there is no sensible way to continue receiving configuration
    //   updates, Envoy will then terminate and apply production config from a
    //   clean slate.
    // * --dry-run-canary. When set, a canary response will never be applied, only
    //   validated via a dry run.
    bool canary = 3;

    // Type URL for resources. This must be consistent with the type_url in the
    // Any messages for resources if resources is non-empty. This effectively
    // identifies the xDS API when muxing over ADS.
    string type_url = 4;

    // For gRPC based subscriptions, the nonce provides a way to explicitly ack a
    // specific DiscoveryResponse in a following DiscoveryRequest. Additional
    // messages may have been sent by Envoy to the management server for the
    // previous version on the stream prior to this DiscoveryResponse, that were
    // unprocessed at response send time. The nonce allows the management server
    // to ignore any further DiscoveryRequests for the previous version until a
    // DiscoveryRequest bearing the nonce. The nonce is optional and is not
    // required for non-stream based xDS implementations.
    string nonce = 5;
}

message DeltaDiscoveryRequest {
  // The node making the request.
  Node node = 1;

  // Type of the resource that is being requested, e.g.
  // ``type.googleapis.com/envoy.api.v2.ClusterLoadAssignment``. This does not need to be set if
  // resources are only referenced via ``xds_resource_subscribe`` and
  // ``xds_resources_unsubscribe``.
  string type_url = 2;

  // DeltaDiscoveryRequests allow the client to add or remove individual
  // resources to the set of tracked resources in the context of a stream.
  // All resource names in the resource_names_subscribe list are added to the
  // set of tracked resources and all resource names in the resource_names_unsubscribe
  // list are removed from the set of tracked resources.
  //
  // *Unlike* state-of-the-world xDS, an empty resource_names_subscribe or
  // resource_names_unsubscribe list simply means that no resources are to be
  // added or removed to the resource list.
  // *Like* state-of-the-world xDS, the server must send updates for all tracked
  // resources, but can also send updates for resources the client has not subscribed to.
  //
  // NOTE: the server must respond with all resources listed in resource_names_subscribe,
  // even if it believes the client has the most recent version of them. The reason:
  // the client may have dropped them, but then regained interest before it had a chance
  // to send the unsubscribe message. See DeltaSubscriptionStateTest.RemoveThenAdd.
  //
  // These two fields can be set in any DeltaDiscoveryRequest, including ACKs
  // and initial_resource_versions.
  //
  // A list of Resource names to add to the list of tracked resources.
  repeated string resource_names_subscribe = 3;

  // A list of Resource names to remove from the list of tracked resources.
  repeated string resource_names_unsubscribe = 4;

  // Informs the server of the versions of the resources the xDS client knows of, to enable the
  // client to continue the same logical xDS session even in the face of gRPC stream reconnection.
  // It will not be populated: [1] in the very first stream of a session, since the client will
  // not yet have any resources,  [2] in any message after the first in a stream (for a given
  // type_url), since the server will already be correctly tracking the client's state.
  // (In ADS, the first message *of each type_url* of a reconnected stream populates this map.)
  // The map's keys are names of xDS resources known to the xDS client.
  // The map's values are opaque resource versions.
  map<string, string> initial_resource_versions = 5;

  // When the DeltaDiscoveryRequest is a ACK or NACK message in response
  // to a previous DeltaDiscoveryResponse, the response_nonce must be the
  // nonce in the DeltaDiscoveryResponse.
  // Otherwise (unlike in DiscoveryRequest) response_nonce must be omitted.
  string response_nonce = 6;

  // This is populated when the previous :ref:`DiscoveryResponse <envoy_v3_api_msg_service.discovery.v3.DiscoveryResponse>`
  // failed to update configuration. The ``message`` field in ``error_details``
  // provides the Envoy internal exception related to the failure.
  Status error_detail = 7;
}

message DeltaDiscoveryResponse {
  // The version of the response data (used for debugging).
  string system_version_info = 1;

  // The response resources. These are typed resources, whose types must match
  // the type_url field.
  repeated Resource resources = 2;

  // field id 3 IS available!

  // Type URL for resources. Identifies the xDS API when muxing over ADS.
  // Must be consistent with the type_url in the Any within 'resources' if 'resources' is non-empty.
  string type_url = 4;

  // Resources names of resources that have be deleted and to be removed from the xDS Client.
  // Removed resources for missing resources can be ignored.
  repeated string removed_resources = 6;

  // The nonce provides a way for DeltaDiscoveryRequests to uniquely
  // reference a DeltaDiscoveryResponse when (N)ACKing. The nonce is required.
  string nonce = 5;
}

message Resource {
  // Cache control properties for the resource.
  // [#not-implemented-hide:]
  message CacheControl {
    // If true, xDS proxies may not cache this resource.
    // Note that this does not apply to clients other than xDS proxies, which must cache resources
    // for their own use, regardless of the value of this field.
    bool do_not_cache = 1;
  }

  // The resource's name, to distinguish it from others of the same type of resource.
  string name = 3;

  // The aliases are a list of other names that this resource can go by.
  repeated string aliases = 4;

  // The resource level version. It allows xDS to track the state of individual
  // resources.
  string version = 1;

  // The resource being tracked.
  google.protobuf.Any resource = 2;

  // Time-to-live value for the resource. For each resource, a timer is started. The timer is
  // reset each time the resource is received with a new TTL. If the resource is received with
  // no TTL set, the timer is removed for the resource. Upon expiration of the timer, the
  // configuration for the resource will be removed.
  //
  // The TTL can be refreshed or changed by sending a response that doesn't change the resource
  // version. In this case the resource field does not need to be populated, which allows for
  // light-weight "heartbeat" updates to keep a resource with a TTL alive.
  //
  // The TTL feature is meant to support configurations that should be removed in the event of
  // a management server failure. For example, the feature may be used for fault injection
  // testing where the fault injection should be terminated in the event that Envoy loses contact
  // with the management server.
  google.protobuf.Duration ttl = 6;

  // Cache control properties for the resource.
  // [#not-implemented-hide:]
  CacheControl cache_control = 7;
}


// Bi-directional streaming interface for messages.
// Subscribe, Ack, Push are represented as upstream messages.
// Monitor, Receipts, SubscribeResponse, AckResponse are represented as downstream messages.
//
// See https://github.com/lyft/envoy-api#apis for a description of the role of
// ADS and how it is intended to be used by a management server. ADS requests
// have the same structure as their singleton xDS counterparts, but can
// multiplex many resource types on a single stream. The type_url in the
// DiscoveryRequest/DiscoveryResponse provides sufficient information to recover
// the multiplexed singleton APIs at the Envoy instance and management server.
service AggregatedDiscoveryService {
    rpc StreamAggregatedResources(stream DiscoveryRequest) returns (stream DiscoveryResponse) {}
    rpc DeltaAggregatedResources(stream DeltaDiscoveryRequest) returns (stream DeltaDiscoveryResponse) {}
}
